/*
 * Copyright (C) 2009 M. Hautle.
 * 
 * This file is part of TrackedBean.
 * 
 * TrackedBean is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option) any later version.
 * 
 * TrackedBean is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License along with TrackedBean. If not, see <http://www.gnu.org/licenses/>.
 */
package ch.trackedbean.copier;

import ch.msoftch.internal.*;
import ch.simpleel.accessors.*;

/**
 * Defines a object holding a mapping.<br>
 * All implementations of this interface must be stateless (so thread safe).
 * 
 * @author M. Hautle
 */
public interface IMappingHolder {
    /**
     * Copies the value from the src object into the dst object.
     * 
     * @param src The other object
     * @param dst The object holding the mapping
     * @param context The mapping context
     * @throws TechnicalException If something goes wrong
     */
    void copySrc2Dst(Object src, Object dst, IMappingContext context) throws TechnicalException;

    /**
     * Copies the value from the dst object into the src object.
     * 
     * @param src The other object
     * @param dst The object holding the mapping
     * @param context The mapping context
     * @throws TechnicalException If something goes wrong
     */
    void copyDst2Src(Object src, Object dst, IMappingContext context) throws TechnicalException;

    /**
     * Returns the value of the mapped source property converted in the destination property format.<br>
     * <b>Depending upon the situation the method may just return null (maybe cause there is no way to read the value).</b>
     * 
     * @param <T> The return type
     * @param src The other object
     * @return The converted value of the source property or null
     * @throws TechnicalException If something goes wrong
     */
    <T> T getSrcValue(Object src) throws TechnicalException;

    /**
     * Returns the value of the destination property converted in the source property format.<br>
     * <b>Depending upon the situation the method may just return null (maybe cause there is no way to read the value).</b>
     * 
     * @param <T> The return type
     * @param dst The object holding the mapping
     * @return The converted value of the destination property or null
     * @throws TechnicalException If something goes wrong
     */
    <T> T getDstValue(Object dst) throws TechnicalException;

    /**
     * Returns the source accessor.
     * 
     * @return The accessor
     */
    IValueAccessor getSourceAccessor();

    /**
     * Returns the destination accessor.
     * 
     * @return The accessor
     */
    IValueAccessor getDestinationAccessor();

    /**
     * Returns the name of the profile to which this mapping belongs.<br>
     * You may use this information in {@link IMappingFilter}s to separate the elements to copy for different usecases (i.e. copy all for initial creation and
     * copy only some attributes for update)
     * 
     * @return The name of the profile
     */
    String getProfile();
}
